<?php
/**
 *
 * @package api
 * @subpackage collections
 * @author $Author$
 * @version $Id: Queue.php 14 2006-11-28 22:05:19Z rdff3 $
 */
 
require_once( "util/Collection.php" );

/**
 * Interface Queue
 *
 * A collection designed for holding elements prior to processing. Besides basic Collection operations, queues provide 
 * additional insertion, extraction, and inspection operations.
 * 
 * Queues typically, but do not necessarily, order elements in a FIFO (first-in-first-out) manner. Among the exceptions are 
 * priority queues, which order elements according to a supplied comparator, or the elements' natural ordering, and LIFO queues 
 * (or stacks) which order the elements LIFO (last-in-first-out). Whatever the ordering used, the head of the queue is that element 
 * which would be removed by a call to remove() or poll(). In a FIFO queue, all new elements are inserted at the tail of the queue. 
 * Other kinds of queues may use different placement rules. Every Queue implementation must specify its ordering properties.
 * 
 * The offer method inserts an element if possible, otherwise returning false. This differs from the Collection.add method, 
 * which can fail to add an element only by throwing an unchecked exception. The offer method is designed for use when failure
 * is a normal, rather than exceptional occurrence, for example, in fixed-capacity (or "bounded") queues.
 * 
 * The remove() and poll() methods remove and return the head of the queue. Exactly which element is removed from the queue is a 
 * function of the queue's ordering policy, which differs from implementation to implementation. The remove() and poll() methods
 * differ only in their behavior when the queue is empty: the remove() method throws an exception, while the poll() method 
 * returns null.
 * 
 * The element() and peek() methods return, but do not remove, the head of the queue.
 *  
 * Queue implementations generally do not allow insertion of null elements, although some implementations, such as LinkedList, 
 * do not prohibit insertion of null. Even in the implementations that permit it, null should not be inserted into a Queue, as 
 * null is also used as a special return value by the poll method to indicate that the queue contains no elements.
 * 
 * Queue implementations generally do not define element-based versions of methods equals and hashCode but instead inherit the 
 * identity based versions from class Object, because element-based equality is not always well-defined for queues with the same
 * elements but different ordering properties.
 * 
 * This interface is a member of the PHP Collections Framework.
 *
 * @package api
 * @subpackage collections
 * @author $Author$
 * @version $Id: Queue.php 14 2006-11-28 22:05:19Z rdff3 $
 */ 
interface Queue extends Collection {

	/**
	 * Retrieves, but does not remove, the head of this queue.
	 *
	 * Retrieves, but does not remove, the head of this queue. This method differs from the peek method only in that it 
	 * throws an exception if this queue is empty.
	 *
	 * @returns Object the head of this queue.
	 * @throws {@link NoSuchElementException} - if this queue is empty.
	 */
	public function element();

	/**
	 * Inserts the specified element into this queue, if possible.
	 *
	 * Inserts the specified element into this queue, if possible. When using queues that may impose insertion restrictions 
	 * (for example capacity bounds), method offer is generally preferable to method Collection.add(E), which can fail to 
	 * insert an element only by throwing an exception.
	 *
	 * @param Object $o the element it insert.
	 * @returns boolean true if it was possible to add the element to this queue, else false.
	 */
	public function offer( Object $o );

	/**
	 * Retrieves, but does not remove, the head of this queue, returning null if this queue is empty.
	 *
	 * @returns Object the head of this queue or null if this queue is empty.
	 */
	public function peek();

	/**
	 * Retrieves and removes the head of this queue, or null  if this queue is empty.
	 *
	 * @returns Object the head of this queue or null if this queue is empty.
	 */
	public function poll();

	/**
	 * Retrieves and removes the head of this queue.
	 *
	 * Retrieves and removes the head of this queue. This method differs from the poll method in that it throws an exception 
	 * if this queue is empty.
	 *
	 * @returns Object the head of this queue
	 * @throws {@link NoSuchElementException} - if this queue is empty.
	 */
	public function removeHead();
}



?>